<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-US">
<head>
<!-- GenHTML revision 25226-->
<meta http-equiv="Content-type" content="text/html; charset=utf-8">
<title>Determining Whether You Need a Custom Component or Renderer - The Java EE 6 Tutorial</title>
<meta name="robots" content="index,follow">
<meta name="robots" content="index,follow">
<meta name="date" content="2011-03-01">
<link rel="stylesheet" type="text/css" href="css/default.css">
<link rel="stylesheet" type="text/css" href="css/ipg.css">
<link rel="stylesheet" type="text/css" href="css/javaeetutorial.css">
</head>

<body>

<table border="0" cellpadding="5" cellspacing="0" width="100%">
<tbody>
   <tr valign="top">
      <td width="400px"><p class="toc level1"><a href="docinfo.html">Document Information</a></p>
<p class="toc level1 tocsp"><a href="gexaf.html">Preface</a></p>
<p class="toc level1 tocsp"><a href="gfirp.html">Part&nbsp;I&nbsp;Introduction</a></p>
<p class="toc level2"><a href="bnaaw.html">1.&nbsp;&nbsp;Overview</a></p>
<p class="toc level2"><a href="gfiud.html">2.&nbsp;&nbsp;Using the Tutorial Examples</a></p>
<p class="toc level1 tocsp"><a href="bnadp.html">Part&nbsp;II&nbsp;The Web Tier</a></p>
<p class="toc level2"><a href="bnadr.html">3.&nbsp;&nbsp;Getting Started with Web Applications</a></p>
<p class="toc level2"><a href="bnaph.html">4.&nbsp;&nbsp;JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="giepx.html">5.&nbsp;&nbsp;Introduction to Facelets</a></p>
<p class="toc level2"><a href="gjddd.html">6.&nbsp;&nbsp;Expression Language</a></p>
<p class="toc level2"><a href="bnaqz.html">7.&nbsp;&nbsp;Using JavaServer Faces Technology in Web Pages</a></p>
<p class="toc level2"><a href="gjcut.html">8.&nbsp;&nbsp;Using Converters, Listeners, and Validators</a></p>
<p class="toc level2"><a href="bnatx.html">9.&nbsp;&nbsp;Developing with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkmaa.html">10.&nbsp;&nbsp;JavaServer Faces Technology Advanced Concepts</a></p>
<p class="toc level2"><a href="bnawo.html">11.&nbsp;&nbsp;Configuring JavaServer Faces Applications</a></p>
<p class="toc level2"><a href="gkiow.html">12.&nbsp;&nbsp;Using Ajax with JavaServer Faces Technology</a></p>
<p class="toc level2"><a href="gkhxa.html">13.&nbsp;&nbsp;Advanced Composite Components</a></p>
<p class="toc level2"><a href="bnavg.html">14.&nbsp;&nbsp;Creating Custom UI Components</a></p>
<div id="scrolltoc" class="onpage">
<p class="toc level3"><a href="">Determining Whether You Need a Custom Component or Renderer</a></p>
<p class="toc level4"><a href="#bnavi">When to Use a Custom Component</a></p>
<p class="toc level4"><a href="#bnavj">When to Use a Custom Renderer</a></p>
<p class="toc level4"><a href="#bnavk">Component, Renderer, and Tag Combinations</a></p>
</div>
<p class="toc level3 tocsp"><a href="bnavt.html">Steps for Creating a Custom Component</a></p>
<p class="toc level3"><a href="bnavu.html">Creating Custom Component Classes</a></p>
<p class="toc level4"><a href="bnavu.html#bnavv">Specifying the Component Family</a></p>
<p class="toc level4"><a href="bnavu.html#bnavw">Performing Encoding</a></p>
<p class="toc level4"><a href="bnavu.html#bnavx">Performing Decoding</a></p>
<p class="toc level4"><a href="bnavu.html#bnavy">Enabling Component Properties to Accept Expressions</a></p>
<p class="toc level4"><a href="bnavu.html#bnavz">Saving and Restoring State</a></p>
<p class="toc level3 tocsp"><a href="bnawa.html">Delegating Rendering to a Renderer</a></p>
<p class="toc level4"><a href="bnawa.html#bnawb">Creating the Renderer Class</a></p>
<p class="toc level4"><a href="bnawa.html#bnawc">Identifying the Renderer Type</a></p>
<p class="toc level3 tocsp"><a href="bnawd.html">Handling Events for Custom Components</a></p>
<p class="toc level3"><a href="bnawe.html">Creating the Component Tag Handler</a></p>
<p class="toc level4"><a href="bnawe.html#bnawf">Retrieving the Component Type</a></p>
<p class="toc level4"><a href="bnawe.html#bnawg">Setting Component Property Values</a></p>
<p class="toc level5"><a href="bnawe.html#bnawh">Getting the Attribute Values</a></p>
<p class="toc level5"><a href="bnawe.html#bnawi">Setting the Component Property Values</a></p>
<p class="toc level4 tocsp"><a href="bnawe.html#bnawl">Providing the Renderer Type</a></p>
<p class="toc level4"><a href="bnawe.html#bnawm">Releasing Resources</a></p>
<p class="toc level3 tocsp"><a href="bnawn.html">Defining the Custom Component Tag in a Tag Library Descriptor</a></p>
<p class="toc level3"><a href="bnaus.html">Creating a Custom Converter</a></p>
<p class="toc level3"><a href="bnaut.html">Implementing an Event Listener</a></p>
<p class="toc level4"><a href="bnaut.html#bnauu">Implementing Value-Change Listeners</a></p>
<p class="toc level4"><a href="bnaut.html#bnauv">Implementing Action Listeners</a></p>
<p class="toc level3 tocsp"><a href="bnauw.html">Creating a Custom Validator</a></p>
<p class="toc level4"><a href="bnauw.html#bnaux">Implementing the Validator Interface</a></p>
<p class="toc level4"><a href="bnauw.html#bnauy">Creating a Custom Tag</a></p>
<p class="toc level5"><a href="bnauw.html#bnauz">Writing the Tag Handler</a></p>
<p class="toc level5"><a href="bnauw.html#bnava">Writing the Tag Library Descriptor</a></p>
<p class="toc level3 tocsp"><a href="bnatt.html">Using Custom Objects</a></p>
<p class="toc level4"><a href="bnatt.html#bnatu">Using a Custom Converter</a></p>
<p class="toc level4"><a href="bnatt.html#bnatv">Using a Custom Validator</a></p>
<p class="toc level4"><a href="bnatt.html#bnatw">Using a Custom Component</a></p>
<p class="toc level3 tocsp"><a href="bnatg.html">Binding Component Values and Instances to External Data Sources</a></p>
<p class="toc level4"><a href="bnatg.html#bnati">Binding a Component Value to a Property</a></p>
<p class="toc level4"><a href="bnatg.html#bnatj">Binding a Component Value to an Implicit Object</a></p>
<p class="toc level4"><a href="bnatg.html#bnatl">Binding a Component Instance to a Bean Property</a></p>
<p class="toc level3 tocsp"><a href="bnatm.html">Binding Converters, Listeners, and Validators to Managed Bean Properties</a></p>
<p class="toc level2 tocsp"><a href="bnafd.html">15.&nbsp;&nbsp;Java Servlet Technology</a></p>
<p class="toc level2"><a href="bnaxu.html">16.&nbsp;&nbsp;Internationalizing and Localizing Web Applications</a></p>
<p class="toc level1 tocsp"><a href="bnayk.html">Part&nbsp;III&nbsp;Web Services</a></p>
<p class="toc level2"><a href="gijti.html">17.&nbsp;&nbsp;Introduction to Web Services</a></p>
<p class="toc level2"><a href="bnayl.html">18.&nbsp;&nbsp;Building Web Services with JAX-WS</a></p>
<p class="toc level2"><a href="giepu.html">19.&nbsp;&nbsp;Building RESTful Web Services with JAX-RS</a></p>
<p class="toc level2"><a href="gjjxe.html">20.&nbsp;&nbsp;Advanced JAX-RS Features</a></p>
<p class="toc level2"><a href="gkojl.html">21.&nbsp;&nbsp;Running the Advanced JAX-RS Example Application</a></p>
<p class="toc level1 tocsp"><a href="bnblr.html">Part&nbsp;IV&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijsz.html">22.&nbsp;&nbsp;Enterprise Beans</a></p>
<p class="toc level2"><a href="gijre.html">23.&nbsp;&nbsp;Getting Started with Enterprise Beans</a></p>
<p class="toc level2"><a href="gijrb.html">24.&nbsp;&nbsp;Running the Enterprise Bean Examples</a></p>
<p class="toc level2"><a href="bnbpk.html">25.&nbsp;&nbsp;A Message-Driven Bean Example</a></p>
<p class="toc level2"><a href="gkcqz.html">26.&nbsp;&nbsp;Using the Embedded Enterprise Bean Container</a></p>
<p class="toc level2"><a href="gkidz.html">27.&nbsp;&nbsp;Using Asynchronous Method Invocation in Session Beans</a></p>
<p class="toc level1 tocsp"><a href="gjbnr.html">Part&nbsp;V&nbsp;Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="giwhb.html">28.&nbsp;&nbsp;Introduction to Contexts and Dependency Injection for the Java EE Platform</a></p>
<p class="toc level2"><a href="gjbls.html">29.&nbsp;&nbsp;Running the Basic Contexts and Dependency Injection Examples</a></p>
<p class="toc level2"><a href="gjehi.html">30.&nbsp;&nbsp;Contexts and Dependency Injection for the Java EE Platform: Advanced Topics</a></p>
<p class="toc level2"><a href="gkhre.html">31.&nbsp;&nbsp;Running the Advanced Contexts and Dependency Injection Examples</a></p>
<p class="toc level1 tocsp"><a href="bnbpy.html">Part&nbsp;VI&nbsp;Persistence</a></p>
<p class="toc level2"><a href="bnbpz.html">32.&nbsp;&nbsp;Introduction to the Java Persistence API</a></p>
<p class="toc level2"><a href="gijst.html">33.&nbsp;&nbsp;Running the Persistence Examples</a></p>
<p class="toc level2"><a href="bnbtg.html">34.&nbsp;&nbsp;The Java Persistence Query Language</a></p>
<p class="toc level2"><a href="gjitv.html">35.&nbsp;&nbsp;Using the Criteria API to Create Queries</a></p>
<p class="toc level2"><a href="gkjiq.html">36.&nbsp;&nbsp;Creating and Using String-Based Criteria Queries</a></p>
<p class="toc level2"><a href="gkjjf.html">37.&nbsp;&nbsp;Controlling Concurrent Access to Entity Data with Locking</a></p>
<p class="toc level2"><a href="gkjia.html">38.&nbsp;&nbsp;Improving the Performance of Java Persistence API Applications By Setting a Second-Level Cache</a></p>
<p class="toc level1 tocsp"><a href="gijrp.html">Part&nbsp;VII&nbsp;Security</a></p>
<p class="toc level2"><a href="bnbwj.html">39.&nbsp;&nbsp;Introduction to Security in the Java EE Platform</a></p>
<p class="toc level2"><a href="bncas.html">40.&nbsp;&nbsp;Getting Started Securing Web Applications</a></p>
<p class="toc level2"><a href="bnbyk.html">41.&nbsp;&nbsp;Getting Started Securing Enterprise Applications</a></p>
<p class="toc level1 tocsp"><a href="gijue.html">Part&nbsp;VIII&nbsp;Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="gijto.html">42.&nbsp;&nbsp;Introduction to Java EE Supporting Technologies</a></p>
<p class="toc level2"><a href="bncih.html">43.&nbsp;&nbsp;Transactions</a></p>
<p class="toc level2"><a href="bncjh.html">44.&nbsp;&nbsp;Resource Connections</a></p>
<p class="toc level2"><a href="bncdq.html">45.&nbsp;&nbsp;Java Message Service Concepts</a></p>
<p class="toc level2"><a href="bncgv.html">46.&nbsp;&nbsp;Java Message Service Examples</a></p>
<p class="toc level2"><a href="gkahp.html">47.&nbsp;&nbsp;Advanced Bean Validation Concepts and Examples</a></p>
<p class="toc level2"><a href="gkeed.html">48.&nbsp;&nbsp;Using Java EE Interceptors</a></p>
<p class="toc level1 tocsp"><a href="gkgjw.html">Part&nbsp;IX&nbsp;Case Studies</a></p>
<p class="toc level2"><a href="gkaee.html">49.&nbsp;&nbsp;Duke's Tutoring Case Study Example</a></p>
<p class="toc level1 tocsp"><a href="idx-1.html">Index</a></p>
</td>
      <td width="10px">&nbsp;</td>
      <td>
         <div class="header">
             <div class="banner">
                <table width="100%" border="0" cellpadding="5" cellspacing="0">
                   <tbody>
                      <tr>
                         <td valign="bottom"><p class="Banner">The Java EE 6 Tutorial
</p></td>
                         <td align="right"  valign="bottom"><img src="graphics/javalogo.png" alt="Java Coffee Cup logo"></td>
                      </tr>
                   </tbody>
                </table>
             </div>

             <div class="header-links">
	         <a href="./index.html">Home</a> | 
<a href="../information/download.html">Download</a> | 
<a href="./javaeetutorial6.pdf">PDF</a> | 
<a href="../information/faq.html">FAQ</a> | 
<a href="http://download.oracle.com/javaee/feedback.htm">Feedback</a>

             </div>
             <div class="navigation">
                 <a href="bnavg.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
                 <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
                 <a href="bnavt.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
             </div>
         </div>

	 <div class="maincontent">      	 
             

<a name="bnavh"></a><h2>Determining Whether You Need a Custom Component or Renderer</h2>
<p>The JavaServer Faces implementation supports a rich set of components and associated renderers,
which are suitable enough for most simple applications. This section helps you to
decide whether you can use standard components and renderers in your application or
need a custom component or custom renderer.</p>



<a name="bnavi"></a><h3>When to Use a Custom Component</h3>
<a name="indexterm-870"></a><p><a name="indexterm-871"></a>A component class defines the state and behavior of a UI component. This
behavior includes converting the value of a component to the appropriate markup, queuing
events on components, performing validation, and other functionality.</p>

<p>You need to create a custom component in the following situations:</p>


<ul><li><p>You need to add new behavior to a standard component, such as generating an additional type of event.</p>

</li>
<li><p>You need a component that is supported by an HTML client but is not currently implemented by JavaServer Faces technology. The current release does not contain standard components for complex HTML components, such as frames; however, because of the extensibility of the component architecture, you can use JavaServer Faces technology to create components like these.</p>

</li>
<li><p>You need to render to a non-HTML client that requires extra components not supported by HTML. Eventually, the standard HTML render kit will provide support for all standard HTML components. However, if you are rendering to a different client, such as a phone, you might need to create custom components to represent the controls uniquely supported by the client. For example, some component architectures for wireless clients include support for tickers and progress bars, which are not available on an HTML client. In this case, you might also need a custom renderer along with the component; or you might need only a custom renderer.</p>

</li></ul>
<p>You do not need to create a custom component in these cases:</p>


<ul><li><p>You need to aggregate components to create a new component that has its own unique behavior. For this case, you can use a composite component to combine existing standard components. For more information on composite components, see <a href="giqzr.html">Composite Components</a> and <a href="gkhxa.html">Chapter&nbsp;13, Advanced Composite Components</a>.</p>

</li>
<li><p><a name="indexterm-872"></a>You simply need to manipulate data on the component or add application-specific functionality to it. In this situation, you should create a managed bean for this purpose and bind it to the standard component rather than create a custom component. See <a href="bnaqm.html">Managed Beans</a> for more information on managed beans.</p>

</li>
<li><p>You need to convert a component&rsquo;s data to a type not supported by its renderer. See <a href="bnast.html">Using the Standard Converters</a> for more information about converting a component&rsquo;s data.</p>

</li>
<li><p>You need to perform validation on the component data. Standard validators and custom validators can be added to a component by using the validator tags from the page. See <a href="bnatc.html">Using the Standard Validators</a> and <a href="bnauw.html">Creating a Custom Validator</a> for more information about validating a component&rsquo;s data.</p>

</li>
<li><p><a name="indexterm-873"></a><a name="indexterm-874"></a><a name="indexterm-875"></a>You need to register event listeners on components. You can either register event listeners on components using the <tt>valueChangeListener</tt> and <tt>actionListener</tt> tags, or you can point at an event-processing method on a managed bean using the component&rsquo;s <tt>actionListener</tt> or <tt>valueChangeListener</tt> attributes. See <a href="bnaut.html">Implementing an Event Listener</a> and <a href="bnavb.html">Writing Managed Bean Methods</a> for more information.</p>

</li></ul>


<a name="bnavj"></a><h3>When to Use a Custom Renderer</h3>
<a name="indexterm-876"></a><p>If you are creating a custom component, you need to ensure, among
other things, that your component class performs these operations:</p>


<ul><li><p><a name="indexterm-877"></a><b>Decoding</b>: Converting the incoming request parameters to the local value of the component</p>

</li>
<li><p><a name="indexterm-878"></a><b>Encoding</b>: Converting the current local value of the component into the corresponding markup that represents it in the response</p>

</li></ul>
<p>The JavaServer Faces specification supports two programming models for handling encoding and decoding:</p>


<ul><li><p><a name="indexterm-879"></a><b>Direct implementation</b>: The component class itself implements the decoding and encoding.</p>

</li>
<li><p><a name="indexterm-880"></a><b>Delegated implementation</b>: The component class delegates the implementation of encoding and decoding to a separate renderer.</p>

</li></ul>
<p>By delegating the operations to the renderer, you have the option of associating
your custom component with different renderers so that you can represent the component
in different ways on the page. If you don&rsquo;t plan to render a
particular component in different ways, it&rsquo;s simpler to let the component class handle
the rendering.</p>

<p>If you aren&rsquo;t sure whether you will need the flexibility offered by separate
renderers but you want to use the simpler direct-implementation approach, you can actually
use both models. Your component class can include some default rendering code, but
it can delegate rendering to a renderer if there is one.</p>



<a name="bnavk"></a><h3>Component, Renderer, and Tag Combinations</h3>
<a name="indexterm-881"></a><p>When you create a custom component, you can create a custom renderer to
go with it. To associate the component with the renderer and to
reference the component from the page, you will also need a custom tag.</p>

<p>In rare situations, however, you might use a custom renderer with a standard
component rather than a custom component. Or you might use a custom tag
without a renderer or a component. This section gives examples of these situations
and summarizes what&rsquo;s required for a custom component, renderer, and tag.</p>

<p>You would use a custom renderer without a custom component if you
wanted to add some client-side validation on a standard component. You would implement the
validation code with a client-side scripting language, such as JavaScript, and then render
the JavaScript with the custom renderer. In this situation, you need a custom
tag to go with the renderer so that its tag handler can register
the renderer on the standard component.</p>

<p>Custom components as well as custom renderers need custom tags associated with them.
However, you can have a custom tag without a custom renderer or custom
component. For example, suppose that you need to create a custom validator that
requires extra attributes on the validator tag. In this case, the custom tag
corresponds to a custom validator and not to a custom component or
custom renderer. In any case, you still need to associate the custom tag
with a server-side object.</p>

<p><a href="#bnavl">Table&nbsp;14-1</a> summarizes what you must or can associate with a custom component, custom
renderer, or custom tag.</p>

<a name="bnavl"></a><p class="caption">Table&nbsp;14-1 Requirements for Custom Components, Custom Renderers, and Custom Tags</p><table><col width="20%"><col width="40%"><col width="39%"><tr><th align="left" valign="top" scope="column"><p>Custom Item</p>

</th>
<th align="left" valign="top" scope="column"><p>Must Have</p>

</th>
<th align="left" valign="top" scope="column"><p>Can Have</p>

</th>
</tr>
<tr><td align="left" valign="top" scope="row"><p>Custom component</p>

</td>
<td align="left" valign="top" scope="row"><p>Custom tag</p>

</td>
<td align="left" valign="top" scope="row"><p>Custom renderer or standard renderer</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>Custom
renderer</p>

</td>
<td align="left" valign="top" scope="row"><p>Custom tag</p>

</td>
<td align="left" valign="top" scope="row"><p>Custom component or standard component</p>

</td>
</tr>
<tr><td align="left" valign="top" scope="row"><p>Custom JavaServer Faces tag</p>

</td>
<td align="left" valign="top" scope="row"><p>Some server-side object, like
a component, a custom renderer, or custom validator</p>

</td>
<td align="left" valign="top" scope="row"><p>Custom component or standard component associated
with a custom renderer</p>

</td>
</tr>
</table>
         </div>
         <div class="navigation">
             <a href="bnavg.html"><img src="graphics/leftButton.gif" border="0" alt="Previous" title="Previous"></a>
             <a href="p1.html"><img src="graphics/upButton.gif" border="0" alt="Contents" title="Contents"></a>
             <a href="bnavt.html"><img src="graphics/rightButton.gif" border="0" alt="Next" title="Next"></a>
         </div>

         <div class="copyright">
      	    <p>Copyright &copy; 2011, Oracle and/or its affiliates. All rights reserved. <a href="docinfo.html">Legal Notices</a></p>
      	 </div>

      </td>
   </tr>
</tbody>
</table>
</body>
</html>

